home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 081-090 / amok89 / xstat1.12 / xstat.doc < prev    next >
Text File  |  1993-11-04  |  17KB  |  541 lines
  1. XStat V1.12 Documentation
  2. =========================
  3.  
  4. Program and documentation are (C) Copyright 1992,1993 by Jürgen Weinelt.
  5.  
  6. IMPORT StdDisclaimer; (* in short: use it at your own risk *)
  7. XStat was carefully tested, but there's certainly plenty of room for bugs.
  8.  
  9. XStat V1.12 is Freeware, non-commercial distribution is o.k. as long as
  10. the following conditions are met:
  11.  
  12.   * Source, executable and documentation must be distributed together
  13.     (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
  14.     and these files must be intact (you're not allowed to make changes).
  15.  
  16.   * Disk librarians: you may charge no more than the current price
  17.     of a single AmigaLibDisk from Fred Fish (Germany: no more than
  18.     8 DM / disk)
  19.  
  20.  
  21.  
  22. XStat requires AmigaOS V37 or later (that's 2.04 or later).
  23.  
  24.  
  25.  
  26. Purpose
  27. =======
  28. XStat extracts statistic information from the Xferstat file created
  29. by some UUCICOs (tested with the SWB variant). The most important
  30. information XStat offers to you is the phone cost for a certain number
  31. of connects.
  32.  
  33.  
  34.  
  35. Installation
  36. ============
  37. Copy the executable "XStat" to a directory in your "Path", preferably UUBIN:
  38.  
  39. There's only one more file that needs to be installed; it's called
  40. "XStat.data", and should be copied to your UULIB: directory.
  41.  
  42. You'll have to edit XStat.data to complete the installation.
  43.  
  44.  
  45.  
  46. XStat.data
  47. ==========
  48. XStat.data contains the phone cost on a "per host" basis, in the following
  49. format:
  50.  
  51. XStat.data file header:
  52. -----------------------
  53. H XSTAT DATA
  54.  
  55. This header must be the first line of XStat.data
  56.  
  57. XStat.data comment line:
  58. ------------------------
  59. # any comments you wish to add to XStat.data
  60.  
  61. You may add comment lines anywhere in your XStat.data file, except before
  62. the file header.
  63.  
  64. XStat.data currency sign info:
  65. ------------------------------
  66. S <currency sign>
  67.  
  68. Tells XStat the currency sign for your country. This line must come before
  69. the first "N"-line. There can be only one "S"-line in your XStat.data file.
  70.  
  71. Examples:
  72.  
  73. # currency sign for the U.S.A.
  74. S $
  75.  
  76. # currency sign for Germany
  77. S DM
  78.  
  79. XStat.data host name info:
  80. --------------------------
  81. N <host name> <host name> ...
  82.  
  83. Starts a new connection cost data record. Must be followed by at least
  84. one "C"-line. <host name> should be the name of a host you're directly
  85. connected to, without any path or domain information.
  86.  
  87. Examples:
  88.  
  89. # my own newsfeed
  90. N imart
  91.  
  92. # my alternate newsfeed
  93. N cbmger
  94.  
  95. Since XStat V1.10, you can use the extended N-line syntax that allows
  96. you to specify multiple host names in a single N-line. All those hosts
  97. will have the same cost information.
  98.  
  99. Example:
  100.  
  101. # several hosts that have the same cost info's
  102. N cbmger brewak forge
  103.  
  104. Since XStat V1.11, you can use several consecutive N-lines.
  105.  
  106. Example:
  107.  
  108. # several hosts that have the same cost info's
  109. N cbmger
  110. N brewak forge
  111.  
  112. Maximum line length of a N-line is 100 characters.
  113.  
  114. Since XStat V1.11, you can also use the reserved host name ".default.".
  115. This cost info will be used for every connect for which the host name
  116. cannot be found in XStat.data.
  117.  
  118. Since XStat V1.12 you can also use the reserved host name ".illegal.".
  119. This name will be used by XStat whenever an XferStat line with empty
  120. host name is encountered.
  121.  
  122. XStat.data connection time/cost info:
  123. -------------------------------------
  124. C <start time> <duration> <price>
  125.  
  126. Tells XStat that between <start time> and <start time of next C-line>
  127. a connection will cost <price> per <duration>. "C"-lines must follow
  128. a "N"-line. <duration> must be in seconds, <price> in the currency of
  129. your choice.
  130.  
  131. The first "C"-line must be for "SU-00:00:00"!
  132. (see exception at LOCAL/IGNORE below)
  133.  
  134. Example:
  135. N imart
  136. C SU-00:00:00 120 0.23
  137. C MO-08:00:00  60 0.23
  138. C MO-18:00:00 120 0.23
  139.  
  140. From Sunday 0:00:00 to Monday 7:59:59, a connection between my
  141. site and my newsfeed "imart" will cost 0.23DM/120sec.
  142.  
  143. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
  144. and my newsfeed "imart" will cost 0.23DM/60sec.
  145.  
  146. With this short example, the connection cost for the rest of the
  147. week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
  148.  
  149. Since Version 1.09 there's another possible C-line syntax... you
  150. can also use "C IGNORE" to tell XStat to ignore all connections from
  151. and to that particular host, or you can use "C LOCAL" to specify a
  152. local connection without connection costs (only the in/out bytes
  153. will be counted in this case). If you use "LOCAL" or "IGNORE", you
  154. may NOT use the normal C-line syntax for that host.
  155. "LOCAL" and "IGNORE" are mutually exclusive.
  156.  
  157.  
  158. Example:
  159. N imart
  160. C IGNORE
  161.  
  162. will cause all connects from/to imart to be ignored.
  163.  
  164.  
  165. Example:
  166. N imart
  167. C LOCAL
  168.  
  169. will cause all connects from/to imart to be counted with cost=0.
  170.  
  171.  
  172.  
  173. Full length example for XStat.data:
  174. -----------------------------------
  175.  
  176. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  177. H XSTAT DATA
  178. #==============================================================================
  179. # XStat connection cost data file
  180. #==============================================================================
  181. #
  182. #------------------------------------------------------------------------------
  183. # currency sign for Germany; S must come before first N
  184. #------------------------------------------------------------------------------
  185. S DM
  186. #
  187. #------------------------------------------------------------------------------
  188. # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
  189. #------------------------------------------------------------------------------
  190. N imart
  191. N .illegal.
  192. C SU-00:00:00 120 0.23
  193. C MO-08:00:00  60 0.23
  194. C MO-18:00:00 120 0.23
  195. C TU-08:00:00  60 0.23
  196. C TU-18:00:00 120 0.23
  197. C WE-08:00:00  60 0.23
  198. C WE-18:00:00 120 0.23
  199. C TH-08:00:00  60 0.23
  200. C TH-18:00:00 120 0.23
  201. C FR-08:00:00  60 0.23
  202. C FR-18:00:00 120 0.23
  203. #
  204. #------------------------------------------------------------------------------
  205. # cbmger, brewak, forge, default:
  206. # connection cost is 0.23/21sec (0.23/42sec night & weekend)
  207. #------------------------------------------------------------------------------
  208. N cbmger
  209. N brewak forge
  210. N .default.
  211. C SU-00:00:00  42 0.23
  212. C MO-08:00:00  21 0.23
  213. C MO-18:00:00  42 0.23
  214. C TU-08:00:00  21 0.23
  215. C TU-18:00:00  42 0.23
  216. C WE-08:00:00  21 0.23
  217. C WE-18:00:00  42 0.23
  218. C TH-08:00:00  21 0.23
  219. C TH-18:00:00  42 0.23
  220. C FR-08:00:00  21 0.23
  221. C FR-18:00:00  42 0.23
  222. #
  223. #------------------------------------------------------------------------------
  224. # bigbang, this is a local (e.g. null-modem) connection
  225. #------------------------------------------------------------------------------
  226. N bigbang
  227. C LOCAL
  228. #
  229. #------------------------------------------------------------------------------
  230. # walker, connects will be ignored
  231. #------------------------------------------------------------------------------
  232. N walker
  233. C IGNORE
  234. #
  235. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  236.  
  237.  
  238.  
  239. Usage
  240. =====
  241. XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
  242.           [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
  243.           [H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR]
  244.  
  245. You may also use the environment variable "XSTATARGS" to specify
  246. parameters. This is very useful if you're using XStat from the
  247. Workbench (XStat doesn't really support Workbench, that's why
  248. there's no icon for it).
  249.  
  250. ?
  251. -
  252. Displays a help message.
  253.  
  254. DATA name
  255. ---------
  256. Tells XStat to read its connection cost data from file <name>.
  257. <name> defaults to "UULIB:XStat.data".
  258.  
  259. FILE name
  260. ---------
  261. Tells XStat to extract the statistic information from file <name>.
  262. <name> defaults to "UUSPOOL:XferStat".
  263.  
  264. V | VERBOSE
  265. -----------
  266. Enables the "verbose" mode. When on, XStat displays short statistics
  267. for every connect found in the Xferstat file. Defaults to "off".
  268. Specify VERBOSE to turn verbose mode on.
  269.  
  270. FD | FROMDATE date
  271. ------------------
  272. Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
  273. You may use any valid AmigaDOS date string, including things like
  274. "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
  275. you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
  276. is [ought to be] currently available to registered developers only) you'll have
  277. to use your locale date specifications, for example "HEUTE" instead of "TODAY"
  278. if you're using the german locale.
  279.  
  280. TD | TODATE date
  281. ----------------
  282. Tells XStat to ignore connects after <date>. <date> defaults to current
  283. date/time. You may use any valid AmigaDOS date string, including things
  284. like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
  285. XStat will add a time string of "23:59:59" internally, you may not do this
  286. yourself.
  287.  
  288. M | MONTH shortdate
  289. -------------------
  290. Tells XStat to ignore FD and TD, and to compute the statistics for the
  291. specified month instead. The month must be given in the format "MMM-YY",
  292. without specifying the day. Example: "MONTH JUN-92" will compute the stats
  293. for June 92. MONTH is inactive as default.
  294.  
  295. NI | NOINCOM
  296. ------------
  297. Tells XStat to suppress evaluation of incoming calls; defaults to off.
  298. Specify "NI" to suppress evaluation of incoming calls. Meaning of this
  299. switch was inverted before version 1.04.
  300.  
  301. NO | NOOUTGO
  302. ------------
  303. Tells XStat to suppress evaluation of outgoing calls; defaults to off.
  304. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
  305. switch was inverted before version 1.04.
  306.  
  307. Q | QUIET
  308. ---------
  309. Tells XStat to suppress non-fatal error messages; defaults to off.
  310. Specify QUIET to suppress non-fatal errors.
  311.  
  312. This is very handy for getting rid of those "(ignoring this one)" messages
  313. for failed connects.
  314.  
  315. H | HOSTNAME
  316. ------------
  317. Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
  318. Starting with V1.06, if <name> contains any valid AmigaDos pattern,
  319. XStat will display subtotals for each host that matches these patterns.
  320.  
  321. Patterns are not case sensitive.
  322.  
  323. Example: XStat hostname (a|x)#?
  324.          will evaluate calls to all hosts that start with an "a" or "x",
  325.          and will display sub-totals for each of those hosts.
  326.  
  327. SE | STDERR
  328. -----------
  329. Tells XStat to send all error messages to StdErr instead of StdOut.
  330. Then you can redirect the statistic output to a file using ">File",
  331. without redirecting the error messages to that file as well.
  332. Redirection defaults to off; specify STDERR to enable redirecting
  333. error messages to StdErr. StdErr is always the console window
  334. XStat was started from. The STDERR option was tested with the
  335. standard AmigaShell only. It *should* work with other shells, too.
  336.  
  337.  
  338.  
  339. XStat's output
  340. ==============
  341.  
  342. Example:
  343.  
  344. > XStat 1.12
  345. > © Copyright 1992,1993 by Jürgen Weinelt
  346. >
  347. > Connection statistics for outgoing calls to host "cbmger":
  348. >
  349. > connects              14          (0 of them were local)
  350. > online time          366 sec      (      27 sec/connect)
  351. > units                 16 units    (   1.143 units/connect)
  352. > cost                3.68 DM       (   0.263 DM/connect)
  353. >
  354. > gross read         81977 bytes    (    5856 bytes/connect)
  355. > gross send         30380 bytes    (    2170 bytes/connect)
  356. > net read           47451 bytes    (    3390 bytes/connect)
  357. > net send           19489 bytes    (    1393 bytes/connect)
  358. >
  359. > av. gross speed      306 cps      (     697 cps peak)
  360. > av. net speed        182 cps      (     550 cps peak)
  361. > av. gross cost    34.344 DM/MB
  362. > av. net cost      57.645 DM/MB
  363. >
  364. >
  365. > Connection statistics for outgoing calls to host "imart":
  366. >
  367. > connects              61          (0 of them were local)
  368. > online time        12800 sec      (     210 sec/connect)
  369. > units                143 units    (   2.344 units/connect)
  370. > cost               32.89 DM       (   0.539 DM/connect)
  371. >
  372. > gross read      11068422 bytes    (  181450 bytes/connect)
  373. > gross send       1260468 bytes    (   20664 bytes/connect)
  374. > net read        10120721 bytes    (  165914 bytes/connect)
  375. > net send          175650 bytes    (    2880 bytes/connect)
  376. >
  377. > av. gross speed      963 cps      (    1218 cps peak)
  378. > av. net speed        804 cps      (     969 cps peak)
  379. > av. gross cost     2.797 DM/MB
  380. > av. net cost       3.349 DM/MB
  381. >
  382. >
  383. > Connection statistics for incoming calls:
  384. > -----------------------------------------
  385. >
  386. > no connects recorded.
  387. >
  388. >
  389. > Connection statistics for outgoing calls:
  390. > -----------------------------------------
  391. >
  392. > connects              75          (0 of them were local)
  393. > ignored connects       0
  394. > online time        13166 sec      (     176 sec/connect)
  395. > units                159 units    (   2.120 units/connect)
  396. > cost               36.57 DM       (   0.488 DM/connect)
  397. >
  398. > gross read      11150399 bytes    (  148672 bytes/connect)
  399. > gross send       1290848 bytes    (   17212 bytes/connect)
  400. > net read        10168172 bytes    (  135576 bytes/connect)
  401. > net send          195139 bytes    (    2602 bytes/connect)
  402. >
  403. > av. gross speed      944 cps      (    1218 cps peak)
  404. > av. net speed        787 cps      (     969 cps peak)
  405. > av. gross cost     3.082 DM/MB
  406. > av. net cost       3.700 DM/MB
  407.  
  408. connects
  409. --------
  410. Number of connects, and number of local (=free) connects
  411. (XStat.data "C LOCAL").
  412.  
  413. ignored connects
  414. ----------------
  415. Number of connects that were IGNOREd (-> XStat.data "C IGNORE").
  416.  
  417. online time
  418. -----------
  419. Total online time, and average online time per connect.
  420.  
  421. units
  422. -----
  423. Phone units consumed, and average phone units consumed per connect.
  424.  
  425. Note: in Germany, a "phone unit" is an indivisible time quantum
  426. (sounds like quantum physics :-). This means even if your connect
  427. is shorter than that, the phone company still charges for the entire
  428. time quantum. Example: unit duration is 60 seconds, connect time was
  429. 97 seconds, phone company charges two units (120 seconds).
  430.  
  431. You can influence the unit duration by editing the XStat.data file;
  432. the <duration> in the "C"-lines tells XStat the unit duration.
  433.  
  434. cost
  435. ----
  436. Total cost, and average cost per connect.
  437.  
  438. gross read
  439. ----------
  440. Total bytes read (including protocol information), and average (per connect).
  441.  
  442. gross send
  443. ----------
  444. Total bytes sent (including protocol information), and average (per connect).
  445.  
  446. net read
  447. --------
  448. Total bytes read (excluding protocol information), and average (per connect).
  449.  
  450. net send
  451. --------
  452. Total bytes sent (excluding protocol information), and average (per connect).
  453.  
  454. av. gross speed
  455. ---------------
  456. Average transmission speed, including protocol overhead, and speed of
  457. fastest connect.
  458.  
  459. av. net speed
  460. -------------
  461. Average transmission speed, excluding protocol overhead, and speed of
  462. fastest connect.
  463.  
  464. av. gross cost
  465. --------------
  466. Average cost per MByte, including protocol overhead.
  467.  
  468. av. net cost
  469. ------------
  470. Average cost per MByte, excluding protocol overhead.
  471.  
  472.  
  473.  
  474. History
  475. =======
  476. V1.12   added ".illegal." feature
  477.         fixed a potential bug in the XferStat parsing code
  478. V1.11   added multiple N-line feature and ".default." host name to XStat.data
  479.           N-Line Syntax.
  480.         fixed a minor bug in the EOF handling of the Xferstat parser.
  481. V1.10   added multiple name feature to XStat.data N-Line syntax
  482.         fixed a small bug in the NI/NO feature
  483. V1.09   added LOCAL and IGNORE to XStat.data C-line syntax
  484. V1.08   added STDERR option, replaced "ø" with "av."
  485. V1.07   list of connection statistics was not sorted correctly. Fixed.
  486. V1.06   extended "hostname" to include pattern matching and "per host" feature
  487. V1.05   added "per host" statistics
  488. V1.04   fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
  489. V1.03   added monthly statistics.
  490. V1.02   added peak brutto/netto cps rating.
  491. V1.01   XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
  492. V1.00   initial release.
  493.  
  494. V0.9x   several test/beta versions, limited circulation
  495.  
  496.  
  497.  
  498. Known problems/bugs
  499. ===================
  500. None so far...
  501.  
  502. Well, actually, there's one problem I can't do anything about... the
  503. online time is not very accurate. That's because the connection start
  504. time seems to state the time the modem says "CONNECT", not the real
  505. start time of the (phone line) connection.
  506.  
  507.  
  508.  
  509. You can contact me through the Usenet:
  510.  
  511.    jow@sun.rz.uni-wuerzburg.de (preferred)
  512.    jow@hcast.adsp.sub.org
  513.    jow@hcast.franken.de
  514.  
  515. Or through the snail mail:
  516.  
  517.    Jürgen Weinelt
  518.    Zur Kanzel 1
  519.    D-8783 Hammelburg
  520.    Germany
  521.  
  522. You might also try posting to comp.sys.amiga.programmer or alt.sys.amiga.uucp,
  523. I'll probably read those newsgroups.
  524.  
  525.  
  526.  
  527. Thanks
  528. ======
  529. The following people contributed suggestions and bug reports:
  530.  
  531.          Christian Balzer
  532.                Kai Bolay
  533.            Hartmut Goebel
  534.   Michael-Wolfgang Hohmann
  535.            Alfredo Jahn V
  536.             Andrew Kopp
  537.            Henning Schmiedehausen
  538.        Kai "wusel" Siering
  539.  
  540. Thank you all.
  541.